/**
 * Copyright (C) 2010 EduSubmit Team (Ersin Er, Sukru Tikves)
 * 
 * This work can be distributed under the terms of 
 * GNU Library General Public License (LGPL) v2.1
 */
package info.edusubmit.services.contracts;

/**
 * @author Sukru
 *
 */
public interface AuthenticationService {
	/**
	 * Authenticates a user with the given password. Returns an authentication token if successful.
	 * @param username User name
	 * @param password Password of the user
	 * @return Authentication token
	 * @throws AuthenticationException when user name or password is incorrect .
	 * @throws AuthLockedException when a set number of retries have been done from the same client machine.
	 */
	String authenticate(String username, String password)
		throws AuthenticationException, AuthLockedException;
	
	/**
	 * Returns whether a given authentication token is valid.
	 * @param token Authentication token 
	 * @return True if token is still valid, False otherwise
	 */
	Boolean isTokenValid(String token);

	/**
	 * Returns the {@link UserInfo} associated with a valid authentication token.
	 * @param token Authentication token
	 * @return Associated {@link UserInfo} structure 
	 * @throws AuthenticationException when token is invalid.
	 */
	UserInfo getUserInfo(String token) throws AuthenticationException;
}
